home *** CD-ROM | disk | FTP | other *** search
/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / database / msgobj10.zip / MSGOBJ.DOC < prev    next >
Text File  |  1993-03-26  |  11KB  |  239 lines
  1. MessageObject 1.0 for Pip message base
  2. by R.Piola, 1993 (wow! it's the first program I release in '93)
  3.  
  4. These sources provide an easy way to access messages stored in PIP format.
  5. Future development includes also an interface to Fido *.MSG and Hudson
  6. QuickMessageBase.
  7.  
  8. They're written in Borland C++ 2.00, and I hope that they will work on most
  9. C++ compilers.
  10.  
  11. SMALLPIP and SMALLPOS are a little message reader and a little message poster
  12. (i.e.: a program that puts a file into a message) to demonstrate how to use
  13. MessageObject. Please notice that they use configuration files created by
  14. PipBase, or Gimme-A-Point, or PipSetup, or Pip* 2.00, and you have to get one 
  15. of these packets in order to have a message base where you can work on.
  16.  
  17. Signal every bug or everything I forgot to: Roberto Piola, fidonet
  18. 2:334/108.57 (or 2:334/306.666), via netmail or via PIPBASE.334 and NET_DEV 
  19. conferences ,or via slow mail (via Roasio 6, 10143 Torino (TO), Italy), or 
  20. by phone: +39-11-7496686 (monday to friday) or +39-121-500663 (on weekends).
  21.  
  22.  
  23. MODULES CONTAINED IN THIS ARCHIVE:
  24.  
  25. AREAS.CPP      To handle BaseDesc.Pip area configuration file
  26. AREAS.H                   '  '
  27. CONFIG.H       MsgObj configuration values (it's only an example!)
  28. MSGOBJ.H       Main include file and area definition
  29. MSGOBJ.CPP     Private functions
  30. MSGOBJAD.CPP   Methods to parse and store addresses
  31. MSGOBJDT.CPP   Methods to parse and process dates
  32. MSGOBJMS.CPP   Methods to process messages
  33. MSGOBJPI.CPP   Methods to compress and uncompress messages in Pip format
  34. MSGOBJ.DOC     This text
  35. MSGOBJ.MAK     A simple makefile
  36. PIPBASE.H      PipBase structure definitions
  37. PIPEXT.H       Some variables where Pip* loads configuration datas; they're
  38.                used by our examples
  39. SMALLPIP.CPP   A little message reader (example)
  40. SMALLPOS.CPP   A little program to send a message (example)
  41.  
  42.  
  43. MESSAGEOBJECT BASICS
  44.  
  45. MessageObject can access messages in Pip message bases (and in future also in 
  46. other message bases) in an easy way.
  47.  
  48. Every area is identified by a number (form 0 to 32767).
  49.  
  50. Every message in every area is identified by a number, starting form 0.
  51.  
  52. MessageObject allows you to read a message (or only its header), insert a 
  53. message into the message base, modify it and delete it, plus some other 
  54. utilities (like finding the last origin line and extracting path and seen-byes
  55. from echomail messages).
  56.  
  57.  
  58. HOW CAN YOU INCORPORATE MSGOBJ IN YOUR PROGRAMS?
  59.  
  60. The first thing you have to do is modifying CONFIG.H file and define how 
  61. MessageObject will interface himself with your configuration files.
  62.  
  63. In particular, you should define (if you don't define them, MsgObj will assume
  64. that Pip* configuration files are used):
  65.  
  66. TEARLINE      a char* to your tear line (without initial ---)
  67. AREATYPE(a)   the type of the area number a: an integer; currently MsgObj 
  68.               supports only areas of type 0 (Pip)
  69. AREAPATH(a)   the path to your message base, backslash terminated; for Pip 
  70.               base it is a constant
  71. AREATAG(a)    char* to the echomail tag of area number a, or to the special
  72.               string "#NETMAIL" for netmail area, "#BAD" for bad messages 
  73.               area, "#DUPES" for dupes area and "#LOCAL" for local non-echo 
  74.               areas (i.e.: areas without a tag)
  75. MYZONE
  76. MYNET
  77. MYNODE
  78. MYPOINT       four unsigned integers and a char* identifying your network
  79. MYDOMAIN      address (in fidonet-technology-based networks)
  80. MYFAKENET     your fakenet, if you use it, or 0 for 4-D addressing
  81. BUFSIZE       the size (in bytes) of the buffer for the message text;
  82.               in most operations, MsgObj will process only messages that will 
  83.               fit in this buffer, truncating them if they will exceed this 
  84.               limit, so keep this number rather large (but remind that some 
  85.               diffuse software cannot handle message longer than 16K, and 
  86.               most string functions are limited to 64K strings; I use 30000 
  87.               bytes, and this is the default)
  88.  
  89. (see also MSGOBJ.H to see default values for these definitions).
  90.  
  91. Second: you have to instantiate an object of the class message_frame: this 
  92. object (I'll call it MsgFrame) will be a window on your message base.
  93.  
  94. Third: use this object; to use it you'll have to place your datas in 
  95. MsgFrame's fields and then call the appropriate MsgFrame function. Functions 
  96. and fields are explained in nect section.
  97.  
  98. Fourth, IMPORTANT: when you exit your program, remember that you'll have to 
  99. call MsgFrame destructor, or Message Object will leave your files open; it 
  100. may destroy part of your message base! Never use abort and, under MS Windows, 
  101. intercept WM_PREPARETOQUIT messages.
  102.  
  103. Most functions reports -1 when they fail, and the ser MsgFrame.lasterror to a 
  104. code; see the table at the end of MSGOBJ.H to interpretate this code.
  105.  
  106. For every doubt, see examples, and then write me.
  107.  
  108.  
  109. MSGOBJ FUNCTIONS AND FIELDS
  110.  
  111. We will consider only the last class defined in MSGOBJ.H; other classes are 
  112. rather simple, and are left to your analisys :-) until I'll have anought 
  113. free time to document them. 
  114.  
  115. Private members are not of interest.
  116.  
  117. lasterror: an integer containg an error code form the last operation, or 
  118.            MSGERR_NOERR if no error has occurred.
  119.  
  120. pipstring,unpipstring,unpipfile,read0,reafile,write0 and writemex: all these
  121.            functions are used internally; I've placed them in the public 
  122.            section only because I use them in my programs and I didn't want 
  123.            to duplicate them. You're free to see them in MSGOBJPI.CPP module, 
  124.            extract them, hide them or do everything you want.
  125.  
  126. find_origin(char*text): this function returns a char* to the last origin of 
  127.            the message pointed by text.
  128.  
  129. area:      an integer with the numebr of the area you want to access.
  130.  
  131. message_number: an integer with the number of the message you want to access.
  132.  
  133. fromaddr,toaddr: addresses of the sender and the recipient of the message;
  134.            these members are object themselves. Consult MSGOBJ.H for their 
  135.            description.
  136.  
  137. attributes,status: message attributes (crash, hold, kill/sent, etc...) in 
  138.            bitmap form and message status (deleted, locked, sent, etc...).
  139.            See PIPBASE.H and FTS-0001 to know the meaning of every bit.
  140.  
  141. cost,times: unuseful and not used. These fields are here only because the 
  142.            have a meaning in other message bases; maybe the will be used in 
  143.            future.
  144.  
  145. text:      this is a pointer to the memory allocated by allocate_text(), or 
  146.            NULL if no space is allocated for your messages; when reading, 
  147.            modifying or posting a message, in this area you'll have to place 
  148.            the message text, a virtually unbounded (except for Intel 80X86 
  149.            64K segment limit <G>), NUL terminated string.
  150.  
  151. textsize:  dimension of the allocated buffer.
  152.  
  153. from,to,subject: strings (not char pointers!) containing the message header;
  154.            self-explanatory.
  155.  
  156. date:      message date and time; it is an object; see MSGOBJ.H for its 
  157.            simple structure.
  158.  
  159. previous,next: integer pointing to the previous and the next messages in the 
  160.            same area with the same subject.
  161.  
  162. post():    this method takes the message contained in {from, to, subject, 
  163.            fromaddr, toaddr, text} fields and inserts it into the area whose 
  164.            number is placed in the area field.
  165.  
  166. modify():  it alters the current message (previously read); to modify a 
  167.            message, read() it, change from, to, subject, fromaddr, toaddr, and
  168.            text[] fields, and then issue a modify()
  169.  
  170. del():     it kills current message (i.e.: message pointed by 
  171.            <area,message_number> fields); you haven't to read() it before 
  172.            del()eting it.
  173.  
  174. read():    it fills all message_frame fields with the message 
  175. or         <area,message_number> (i.e.: to read a message, assign area and
  176. read(0)    message_number fields, and then issue a read()). If text is not 
  177.            allocated, read() will fill only from, to, subject and date 
  178.            fields.
  179.  
  180. read(1):   exactly like read(), but you force a message re-reading (read() 
  181.            will not access disk if you haven't modified the message number
  182.            since the last call of read().
  183.  
  184. allocate_text(size): allocates a message buffer of the specified size; you've
  185.            always to check if it returns -1 (no memory available); a 0 is 
  186.            returned if text buffer is allocated; do not directly assegnate 
  187.            message_frame::text pointer to a malloc-ed block, but use this 
  188.            function, especially under MS Windows; if no size is specified 
  189.            (i.e.: you call allocate_text()), BUFSIZE bytes are assumed; if 
  190.            you call allocate_text() when text is already allocated, this 
  191.            command will have no effect; notice that size is a long integer,
  192.            but I don't guarantee that buffers >64K will work with all string 
  193.            operations (strings longer than 64 Kb are expressly prohibited on 
  194.            my MS Windows Programming manuals).
  195.  
  196. deallocate_text(): it deallocates allocated text buffer; use always this 
  197.            function, and never a free(message_frame::text).
  198.  
  199. isolate_seen_by(AUDIT*sb,int&ns,int maxns,AUDIT*pth,int&np,int maxnp): this 
  200.            function extracts seen-byes and path from a message (removing 
  201.            them from message text!); AUDIT structure is described somewhere 
  202.            in haeader files; you must pass pointers to arrays of maxns 
  203.            elements that will contain seen-byes and maxnp elements for path 
  204.            informations; at return, ns and np will contain the number of 
  205.            effectively read seen-bye and path elements.
  206.  
  207. highest_message(void): this returns the number of the last message in the 
  208.            current (i.e.: the area you set with message_frame::area=xxx) 
  209.            area; if area is empty it returns -1.
  210.  
  211. total_messages(void): this returns the total number of messages present in 
  212.            the current area; for Pip Base it's always highest_message()+1.
  213.  
  214. message_frame(): the constructor; it's called automatically; it does not 
  215.            allocate text buffer, nor position you on a particular area or 
  216.            message.
  217.  
  218. ~message_frame(): the destructor; usually, it's called automatically by BC++ 
  219.            standard exit() function: it closes open files and eventually 
  220.            deallocates text.
  221.  
  222. Most pointers are huge. If you don't compile under a huge memory model, 
  223. you'll have to insert some casting when calling MessageObject.
  224.  
  225.  
  226. ROYALTIES AND DISTRIBUTION
  227.  
  228. You're encouraged to distribute MessageObject without modifying it.
  229. If you alter (improving) it, please send a modified and commented copy to the
  230. author.
  231.  
  232. You may include MessageObject code into every program you write, and distribute
  233. it. No royalties are due if your program is public domain; if it is shareware,
  234. consider the idea of offering me something (a share on every registration, or
  235. an una-tantum gift... everything you want and you think it may made me happy);
  236. if it is a commercial ($$$) software, please contact me.
  237.  
  238. Please let me know every application you create with this tool.
  239.